<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Using dbstl efficiently</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="stl.html" title="Chapter 8. Standard Template Library API" />
    <link rel="prev" href="stl_container_specific.html" title="Dbstl container specific notes" />
    <link rel="next" href="stl_memory_mgmt.html" title="Dbstl memory management" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Using dbstl
        efficiently</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="stl_container_specific.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 8. Standard Template Library API</th>
          <td width="20%" align="right"> <a accesskey="n" href="stl_memory_mgmt.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="stl_efficienct_use"></a>Using dbstl
        efficiently</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="stl_efficienct_use.html#idm140526455278656">Using iterators efficiently</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="stl_efficienct_use.html#idm140526455280320">Using containers efficiently</a>
            </span>
          </dt>
        </dl>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idm140526455278656"></a>Using iterators efficiently</h3>
            </div>
          </div>
        </div>
        <p>
            To make the most efficient possible use of iterators:
        </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                    Close an iterator's cursor as soon as possible. 
                </p>
              <p> 
                    Each iterator has an open cursor associated
                    with it, so when you are finished using the
                    iterator it is a good habit to explicitly close
                    its cursor. This can potentially improve
                    performance by avoiding locking issues, which will
                    enhanced concurrency. Dbstl will close the cursor
                    when the iterator is destroyed, but you can close
                    the cursor before that time. If the cursor is
                    closed, the associated iterator cannot any longer
                    be used.
                </p>
              <p> 
                    In some functions of container classes, an
                    iterator is used to access the database, and its
                    cursor is internally created by dbstl. So if you
                    want to specify a non-zero flag for the
                    <code class="methodname">Db::cursor()</code> call,
                    you need to call the container's
                    <code class="function">set_cursor_open_flag()</code>
                    function to do so. 
                </p>
            </li>
            <li>
              <p>
                    Use const iterators where applicable.
                </p>
              <p>
                    If your data access is read only, you are
                    strongly recommended to use a const iterator. In
                    order to create a const iterator, you must use a
                    const reference to the container object. For
                    example, supposed we have: 
                </p>
              <pre class="programlisting">db_vector&lt;int&gt; intv(10);</pre>
              <p>
                    then we must use a:
                </p>
              <pre class="programlisting">const db_vector&lt;int&gt;&amp; intv_ref = intv;</pre>
              <p> 
                    reference to invoke the const begin/end
                    functions.
                    <code class="methodname">intv_ref.begin()</code> will
                    give you a const iterator. You can use a const
                    iterator only to read its referenced data
                    elements, not update them. However, you should
                    have better performance with this iterator using,
                    for example, either
                    <code class="literal">iterator::operator*</code> or
                    <code class="literal">iterator::operator-&gt;member</code>.
                    Also, using array indices like
                    <code class="literal">intv_ref[i]</code> will also
                    perform better. 
                </p>
              <p> 
                    All functions in dbstl's containers which
                    return an iterator or data element reference have
                    two versions — one returns a const
                    iterator/reference, the other returns an
                    iterator/reference. If your access is read only,
                    choose the version returning const
                    iterators/references.
                </p>
              <p>
                    Remember that you can only use a const
                    reference to a container object to call the const
                    versions of <code class="literal">operator*</code> and
                    <code class="literal">operator[]</code>. 
                </p>
              <p>
                    You can also use the non-const container object
                    or its non-const reference to create a read only
                    iterator by passing <code class="literal">true</code> to the
                    <span class="bold"><strong>readonly</strong></span>
                    parameter in the container's
                    <code class="methodname">begin()</code> method.
                </p>
            </li>
            <li>
              <p>
                    Use pre-increment/pre-decrement rather than
                    post-increment/post-decrement where possible 
                </p>
              <p> 
                    Pre-increment operations are more efficient
                    because the <code class="literal">++iterator</code> avoids
                    two iterator copy constructions. This is true when
                    you are using C++ standard STL iterators as well.
                </p>
            </li>
            <li>
              <p>
                    Use bulk retrieval in iterators 
                </p>
              <p> 
                    If your access pattern is to go through the
                    entire database read only, or if you are reading a
                    continuous range of the database, bulk retrieval
                    can be very useful because it returns multiple
                    key/data pairs in one database call. But be aware
                    that you can only read the returned data, you can
                    not update it. Also, if you do a bulk retrieval
                    and read the data, and simultaneously some other
                    thread of control updates that same data, then
                    unless you are using a serializable transaction,
                    you will now be working with old data.
                </p>
            </li>
          </ul>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idm140526455280320"></a>Using containers efficiently</h3>
            </div>
          </div>
        </div>
        <p>
            To make the most efficient possible use of containers: 
        </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                    Avoid using container methods that return
                    references. These because they are a little more
                    expensive. 
                </p>
              <p> 
                    To implement reference semantics, dbstl has to
                    wrap the data element with the current key/data
                    pair, and must invoke two iterator copy
                    constructions and two Berkeley DB cursor
                    duplications for each such a call. This is true of
                    non-const versions of these functions:
                </p>
              <table class="simplelist" border="0" summary="Simple list">
                <tr>
                  <td>
                        <code class="methodname">db_vector&lt;T&gt;::operator[]()</code>
                    </td>
                </tr>
                <tr>
                  <td>
                        <code class="methodname">db_vector&lt;T&gt;::front()</code>
                    </td>
                </tr>
                <tr>
                  <td>
                        <code class="methodname">db_vector&lt;T&gt;::back()</code>
                    </td>
                </tr>
                <tr>
                  <td>
                        <code class="methodname">db_vector&lt;T&gt;::at()</code>
                    </td>
                </tr>
                <tr>
                  <td>
                        <code class="methodname">db_map&lt;&gt;::operator[]()</code>
                    </td>
                </tr>
              </table>
              <p> 
                    There are alternatives to these functions,
                    mainly through explicit use of iterators. 
                </p>
            </li>
            <li>
              <p> 
                    Use const containers where possible. 
                </p>
              <p> 
                    The const versions of the functions listed
                    above have less overhead than their non-const
                    counterparts. Using const containers and iterators
                    can bring more performance when you call the const
                    version of the overloaded container/iterator
                    methods. To do so, you define a const container
                    reference to an existing container, and then use
                    this reference to call the methods. For example,
                    if you have:
                </p>
              <pre class="programlisting">db_vector&lt;int&gt; container int_vec</pre>
              <p> 
                    then you can define a const reference to
                    <code class="literal">int_vec</code>: 
                </p>
              <pre class="programlisting">const db_vector&lt;int&gt;&amp; int_vec_ref; </pre>
              <p> 
                    Then you use
                    <code class="methodname">int_vec_ref.begin()</code>
                    to create a const iterator,
                    <code class="literal">citr</code>. You can now can use
                    <code class="literal">int_vec_ref</code> to call the
                    const versions of the container's member
                    functions, and then use <code class="literal">citr</code> to
                    access the data read only. By using
                    <code class="literal">int_vec_ref</code> and
                    <code class="literal">citr</code>, we can gain better
                    performance.
                </p>
              <p> 
                    It is acceptable to call the non-const versions
                    of container functions that return non-const
                    iterators, and then assign these return values to
                    const iterator objects. But if you are using
                    Berkeley DB concurrent data store (CDS), be sure
                    to set the <span class="bold"><strong>readonly</strong></span>
                    parameter for each container method that returns an iterator to
                    <code class="literal">true</code>. This is because each
                    iterator corresponds to a Berkeley DB cursor, and
                    so for best performance you should specify that
                    the returned iterator be read-only so that the
                    underlying cursor is also read-only. Otherwise,
                    the cursor will be a writable cursor, and
                    performance might be somewhat degraded. If you are
                    not using CDS, but instead TDS or DS or HA, there
                    is no distinction between read-only cursors and
                    read-write cursors. Consequently, you do not need
                    to specify the <span class="bold"><strong>readonly</strong></span> parameter at all.
                </p>
            </li>
          </ul>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="stl_container_specific.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="stl.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="stl_memory_mgmt.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Dbstl container specific
        notes </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Dbstl memory management</td>
        </tr>
      </table>
    </div>
  </body>
</html>
